Inside Macintosh: QuickDraw GX Graphics /

Chapter 2 - Geometric Shapes / Geometric Shapes Reference

Functions / Editing Shape Geometries

GXSetPolygonParts

You can use the GXSetPolygonParts function to replace a range of geometry information in the geometry of a polygon shape with information from a specified polygon structure.

void GXSetPolygonParts(gxShape target, long index, long count, 
                       const gxPolygons *data, 
                       gxEditShapeFlag flags);

target

A reference to the polygon shape whose geometry you want to edit.

index

The geometry index of the first geometric point to replace. A value of 0 indicates that the new information should be inserted after the final geometric point in the target shape's geometry.

count

The number of the geometric points to replace. A value of 0 indicates that no geometric points should be replaced; instead, the new information is inserted before the geometric point indicated by the index parameter. If you pass the gxSelectToEnd constant for this parameter, all geometric points starting with the geometric point indicated by the index parameter are replaced.

data

A pointer to a polygon structure containing the new geometry information.

flags

A set of flags that determine how the new information is inserted in the existing geometry.

DESCRIPTION

The GXSetPolygonParts function replaces geometry information in the target shape's geometry with the information pointed to by the data parameter. The index and count parameters determine what part of the original geometry is replaced. The flags parameter determines how the new information is inserted in the geometry.

The data parameter contains a pointer to the geometry information to be copied into the target shape's geometry. If you pass the gxSetToNil constant for this parameter, no new information is copied in; in this case, this function removes the indicated geometric points instead of replacing them.

The index parameter indicates the first geometric point to be replaced. If you pass a value of 0 for this parameter, no geometric points are replaced. Instead, this function inserts the new geometry information after the last geometric point of the target shape's original geometry. If you pass 0 for this parameter, you must pass 0 or the gxSelectToEnd constant for the count parameter.

The count parameter indicates how many geometric points in the original geometry should be replaced. If you pass a value of 0 for this parameter, no geometric points are replaced; instead, this function inserts the new geometry information before the geometric point indicated by the index parameter. If you pass the gxSelectToEnd constant for this parameter, the function replaces all geometric points in the original geometry starting with the geometric point indicated by the index parameter.

When this function inserts the new geometry information, it retains the contour breaks contained in the gxPolygons structure specified by the data parameter. For example, if you provide a gxPolygons structure that contains two contours, the break between those contours remains when the new geometric points are inserted in the target shape's geometry.

The flags parameter indicates how you want the function to merge the first geometric point and the last geometric point of the gxPolygons structure into the target shape's geometry. The possible flags are

gxBreakNeitherEdit         = 0
gxBreakLeftEdit            = 0x01
gxBreakRightEdit           = 0x02
gxRemoveDuplicatePoints    = 0x04

The gxBreakNeitherEdit value indicates that the first geometric point of the gxPolygons structure should be merged into the preceding contour of the target shape's geometry and the final geometric point of the gxPolygons structure should be merged into the following contour.

The gxBreakLeftEdit flag indicates that the first geometric point of the gxPolygons structure should begin a new contour in the target shape's geometry. The gxBreakRightEdit flag indicates that the geometric point in the target shape that follows the final geometric point of the gxPolygons structure (after the new information is inserted) should begin a new contour.

The gxRemoveDuplicatePoints flag indicates that this function should, when inserting the information from the gxPolygons structure, remove the first geometric point of this structure if it exactly matches the preceding geometric point. Similarly, this flag indicates that the final geometric point of the gxPolygons structure should be removed if it exactly matches the subsequent geometric point in the target shape's geometry.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
number_of_points_exceeds_implementation_limit
number_of_contours_exceeds_implementation_limit
size_of_polygon_exceeds_implementation_limit
illegal_type_for_shape	(debugging version)
inconsistent_parameters	(debugging version)
index_is_less_than_zero	(debugging version)
count_is_less_than_zero	(debugging version)
shape_access_not_allowed	(debugging version)
Warnings
index_out_of_range
count_out_of_range

SEE ALSO

For an example that uses this function, see "Editing Polygon Parts" beginning on page 2-82.

For a discussion of polygons, see "Polygon Shapes" on page 2-22.

For the definition of the gxPolygons structure, see page 2-106.

For information about other functions that allow you to edit information in shape geometries, see the description of the GXSetShapePoints function on page 2-142 and the description of the GXSetShapeParts function on page 2-154.

To copy parts of a polygon shape's geometry, use the GXGetPolygonParts function, which is described on page 2-144.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help